Text Media Handler Functions(IM:Q)

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Text Media Handler Functions
This section describes the functions and structure associated with the text media handler, which allows you to display text in movies. You can use text media handlers to

add plain or styled text samples to a movie
indicate scrolling and highlighting properties for the text
search for text
highlight specified text

A particular text sample has a default font, size, typeface, and color as well as a location (text box) within the track bounds to be drawn. The data format allows you to include style run information for the text. You can set flags to clip the display to the text box, inhibit automatic scaling of text as the track bounds are scaled, scroll the text, and specify if text is to be displayed at all.
The Movie Toolbox provides functions to help you add text samples to a track. You can use the AddTextSample function to add text to a media. The AddTESample function allows you to specify a TextEdit handle (which may have multiple style runs) to be added to a media. The AddHiliteSample function allows you to indicate highlighting for text that has just been added with the AddTextSample or AddTESample function. For more information on styled text, style runs, and TextEdit, see Inside Macintosh: Text.
The format of the text data that is added to the media is a 16-bit length word followed by the text. The length word specifies the number of bytes in the text. Optionally, one or more atoms of additional data may follow. An atom is structured as a 32-bit length word followed by a 32-bit type followed by some data. The length word includes the size of the data as well as the length and type fields (in other words, the size of the data plus 8).
Text atom types include the style atom ('styl'), the shrunken text box atom ('tbox'), the highlighting atom ('hlit'), the scroll delay atom ('dlay'), and the highlight color atom ('hclr').
The format of the style atom is the same as TextEdit's StScrpRec data type. A StScrpRec data type is a short integer specifying the number of style runs followed by that number of ScrpSTElement data types, each specifying a different style run.
The shrunken text box atom is added when you set the dfShrinkTextBoxToFit display flag (in the AddTextSample or AddTESample function). Its format is simply the rectangle of the shrunken box (16 bytes total, including length and type).
The highlighting atom is added if the hiliteStart and hiliteEnd parameters are set appropriately in the AddTextSample or AddTESample function. When AddHiliteSample is called, an empty text sample (the first 2 bytes are 0) with a highlighting atom is added to the media. The format is two long integers indicating the start and end of the highlighting (16 bytes total).
The scroll delay atom specifies the scroll delay for a sample. It is a long value that specifies the delay time. It consists of 12 bytes, including the length and type fields.
The highlight color atom specifies the highlight color for a sample. Its format is an RGBColor data type (that is, 2 bytes red, 2 bytes green, and 2 bytes blue). It consists of 14 bytes, including the length and type fields.
The text description structure is defined as follows:
typedef struct TextDescription {
   long           size;             /* total size of this text    
                                        description structure */
   long           type;             /* type of data in this
                                        structure such as 
                                        'text' */
   long           resvd1;           /* reserved for use by
                                        Apple--set to 0 */
   long           resvd2;           /* reserved for use by
                                        Apple--set to 0 */
   short          dataRefIndex;     /* index to data references */
   long           displayFlags;     /* display flags for text */
   long           textJustification;
                                    /* text justification flags */
   RGBColor       gColor;           /* background color */
   Rect           defaultTextBox;   /* location of the text within
                                        track bounds */
   ScrpSTElement  defaultStyle;
                                    /* default style-- 
                                        TextEdit structure */
} TextDescription, *TextDescriptionPtr, **TextDescriptionHandle;
Field Description

size
Defines the total size of this text description structure.
type
Indicates the type (data type 'text').
resvd1
Reserved for use by Apple. This field must be set to 0.
resvd2
Reserved for use by Apple. This field must be set to 0.
displayFlags
Contains the flags that specify how the text is to be displayed.
textJustification

Contains the constant that specifies how the text is to be aligned.
bgColor
Specifies the background color for the text display.
defaultTextBox

Indicates the location of the text within track boundaries.
defaultStyle
Provides a TextEdit data structure (defined by the ScrpSTElement data type) that specifies the default style for the text display.
The AddTextSample, AddTESample, and AddHiliteSample functions described in the sections that follow convert text into the text media format and add it to the media. To use these functions, you need to

create a text track and media
call the BeginMediaEdits function
call the AddTextSample, AddTESample, or AddHiliteSample function, as appropriate
call the EndMediaEdits function
call the InsertMediaIntoTrack function

The movie import and export components help to get common data types (such as 'PICT' or 'snd ') into and out of movies easily. The text import component allows you to get text into a movie using the following principles:

If you try to paste text, the text is inserted at the current position. The text import component tries to find an existing text track that fits the text.
If no text tracks exist and there is an insertion operation, the newly created text track has the same position and size as the movie box.
If there is an addition operation (using the Shift key), the new track is added below the movie at a height that fits the text.
If a text track exists but the text does not fit, a new text track with sufficient height to accommodate the text is created in the same location as the existing one.
If you hold down the Option key when you paste, the text is added in parallel at some default duration.
If you hold down both the Option and Shift keys, the duration of the text is determined by the length of the current selection.
If style information is on the Clipboard, it is used; otherwise, the text appears in the default 12-point application font, centered, in white on a black background.

If you want more control over how the text is added (for example, if you want to set some display flags or a new track position), your application must

intercept the text paste
instantiate its own text import component using the component type 'eat ' and component subtype 'TEXT'
use functions including MovieImportSetSampleDuration, MovieImportSetSampleDescription, MovieImportSetDimensions, and MovieImportSetAuxilliaryData (with 'styl' and a StScrpHandle
data type)
call the MovieImportHandle function with the text data
adjust the location of the track, if desired (since the text import component may place it below the movie box)

For details on the movie import and export components, see Inside Macintosh: QuickTime Components.
The Movie Toolbox provides functions that allow you to search for and highlight text. You can use the FindNextText function to search for text in a text track, and the HiliteTextSample function to highlight specified text in a text track.
You can use the SetTextProc function (also described in this section) to specify a customized function whenever a new text sample is added to a movie. The application-defined text function MyTextProc is described in "Text Functions" on page 2-342.

Subtopics

AddTextSample

AddTESample

AddHiliteSample

FindNextText

HiliteTextSample

SetTextProc